Skip to content

docs: add Python testing best practices guide#6

Open
agent-kurouto[bot] wants to merge 2 commits intodevfrom
feat/plt-1027-python-testing-best-practices-guide
Open

docs: add Python testing best practices guide#6
agent-kurouto[bot] wants to merge 2 commits intodevfrom
feat/plt-1027-python-testing-best-practices-guide

Conversation

@agent-kurouto
Copy link
Contributor

@agent-kurouto agent-kurouto bot commented Mar 19, 2026

Summary

  • Adds docs/testing.md — a comprehensive Python testing best practices guide covering unit tests, integration tests, E2E tests, property-based testing (Hypothesis), mocking & patching (pytest-mock), test organisation, and coverage
  • Updates README.md to include the new guide in the contents table

Guide sections

  1. Unit Tests — pytest basics, fixtures (with scope table), @pytest.mark.parametrize
  2. Integration Tests — testcontainers, marking tests, selective test runs
  3. End-to-End Tests — httpx async client, CLI subprocess testing
  4. Property-Based Testing — Hypothesis @given, strategies, shrinking
  5. Mocking & Patching — unittest.mock, pytest-mock, when not to mock
  6. Test Organisation — conftest.py, naming conventions, pyproject.toml config
  7. Coverage — pytest-cov, threshold enforcement, HTML reports, # pragma: no cover
  8. Worked Example — complete mini-project tying all sections together

Test plan

  • Review docs/testing.md for accuracy and consistency with existing guides
  • Verify all code examples are syntactically correct
  • Confirm README.md contents table renders correctly
  • Check all internal links resolve

Closes PLT-1027

🤖 Generated with Claude Code

@agent-kurouto
docs: add Python testing best practices guide
40e91c8 
Add docs/testing.md covering unit tests, integration tests, E2E tests,
property-based testing with Hypothesis, mocking with pytest-mock,
test organisation (conftest.py, markers, pyproject.toml config),
coverage targets with pytest-cov, and a complete worked example.

Update README.md contents table with a link to the new guide.

Closes PLT-1027

Co-Authored-By: agent-kurouto[bot] <268466204+agent-kurouto[bot]@users.noreply.github.com>
eywalker
eywalker requested changes Mar 19, 2026
View reviewed changes
docs/testing.md
---

## Table of Contents

Copy link

@eywalker eywalker Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we add a section that discusses what tests users should do if they are just getting started. Listing all different kinds of available tests can be overwhelming

@agent-kurouto
docs(testing): add 'Where to Start' section for beginners
54cc0a8 
Add a new Section 1 that gives newcomers a clear, incremental path
into testing: install pytest → unit test core logic → add a smoke
integration test → reach for the advanced tools only as needed.

Renumber all subsequent sections accordingly and update the ToC.

Addresses review feedback on PLT-1027.
@agent-kurouto
Copy link
Contributor Author

agent-kurouto bot commented Mar 19, 2026

Response to review comments

@eywalker — Can we add a section that discusses what tests users should do if they are just getting started. Listing all different kinds of available tests can be overwhelming

Done! Added a new Section 1 — "Where to Start" (commit 54cc0a8) with an explicit four-step on-ramp for beginners:

  1. Step 1 — Install pytest and write a single test (the absolute minimum to get going)
  2. Step 2 — Cover core business logic with unit tests, focusing on the scenarios that matter most
  3. Step 3 — Add one or two smoke integration tests once unit tests are solid
  4. Step 4 — Reach for E2E tests, property-based tests, mocking, and coverage enforcement only when a specific need arises, with a bullet-point guide on when that is:
    • Break a workflow → E2E test
    • Discover an unexpected edge-case bug → property-based test
    • Slow/flaky test from an external service → mocking
    • Prevent coverage regression in CI → coverage threshold

The existing sections are unchanged and now serve as the reference material that "Where to Start" links readers to when they're ready.

PR summary

This PR adds docs/testing.md — a new standalone Python testing best practices guide for nauticalab/python-best-practices. It follows the same structure and style as the existing docs/logging.md.

What's covered

Section Content
Where to Start Beginner-friendly four-step on-ramp
Unit Tests pytest fixtures, parametrize, scopes
Integration Tests testcontainers, test markers, selective runs
End-to-End Tests httpx async client, CLI subprocess testing
Property-Based Testing Hypothesis @given, strategies, shrinking
Mocking & Patching unittest.mock, pytest-mock, when not to mock
Test Organisation conftest.py, naming conventions, pyproject.toml config
Coverage pytest-cov, CI threshold, HTML reports, # pragma: no cover
Worked Example Complete mini-project tying all sections together

README.md has also been updated to include the new guide in the contents table.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@eywalker eywalker eywalker requested changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@eywalker